/*
 * MIT License
 *
 * Copyright (c) 2020 wen.gu <454727014@qq.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/***************************************************************************
 * Name: abort.h
 *
 * Purpose: This section describes the APIs that constitute the explicit 
 *          abnormal termination facility
 *
 * Developer:
 *   wen.gu , 2020-04-20
 *
 * TODO:
 *
 ***************************************************************************/

#ifndef __ARA_CORE_ABORT_H__
#define __ARA_CORE_ABORT_H__
/******************************************************************************
 **    INCLUDES
 ******************************************************************************/




/******************************************************************************
 **    MACROS
 ******************************************************************************/


/******************************************************************************
 **    TYPE DEFINITIONS
 ******************************************************************************/
namespace ara
{
namespace core
{
using AbortHandler = void (*)() /*noexcept*/;
/******************************************************************************
 **    CLASSES/FUNCTIONS DEFINITIONS
 ******************************************************************************/

/**
 * @brief Set a custom global Abort handler function and return the previously installed one.
 *        By setting nullptr, the implementation may restore the default handler instead.
 *        This function can be called from multiple threads simultaneously; these calls are performed in
 *        an implementation-defined sequence
 *
 *@param  a custom Abort handler (or nullptr)
 *
 * @return  the previously installed Abort handler (or nullptr if none was installed)
 */
AbortHandler SetAbortHandler(AbortHandler handler) noexcept;

/**
 *@brief Terminate the current process abnormally.
 *       Before terminating, a log message with FATAL severity is being output, which includes the text
 *       given as argument to this function.
 *       This function will never return to its caller. The stack is not unwound: destructors of variables
 *       with automatic storage duration are not called.
 *       An application can add exactly one own "hook" into this mechanism by calling the function Set
 *       AbortHandler(). If such an Abort handler has been installed, it is called in turn when Abort() is
 *       invoked, but after the log message has been output. If there is no custom Abort handler, or if
 *       there is one and it returns, then the invocation of this function will terminate the process via
 *       std::abort().
 *       Any call of this function that is performed while another call is already in progress will block the
 *       calling thread.
 *       The text argument is expected to point to a null-terminated string with static storage duration.
 *       Note: The type of the text argument is a raw pointer (instead of a more "modern" type such as
 *       StringView) in order to increase the chances that the function call succeeds even in situations
 *       when e.g. the stack has been corrupted.
 *
 *@param a custom text to include in the log message being output
 */

void Abort(char const* text) noexcept;



} /** namespace core */
} /** namespace ara */

#endif /** !__ARA_CORE_ABORT_H__ */

